3 Narrative Text
Beyond the YAML header, there are two other essential portions to Quarto files: narrative text and (reproducible) code. This section focuses on how you format/style your narrative text.
There are two approaches you can take to format/style your narrative text. In class, you saw how to do this using RStudio Desktop’s Visual editor. This displays your document in a What-You-See-Is-What-You-Get (WYSIWYG) style simple editor that has buttons much like what you have in MyOpenMath for essay questions or might encounter in Google Docs. For this guide, I’m going to show how to format your text when you are in the Source view of a Quarto document. (This approach will also work if you are using another IDE that doesn’t support a visual editor.) Your formatting draws upon Markdown syntax.
Markdown syntax also works on GitHub. This includes Markdown files (e.g., readme.md), commit messages, issues, pull request details, etc.
3.1 Headings
Many students often think about headings as being a stylistic element and to a certain extent this is true. However, headings also serve an important structural purpose: headings help readers build their sense of how the different parts of the document connect to each other in a hierarchical fashion. Throughout this guide, I’ve been using (numbered) headings to communicate the guide’s structure and help you get a sense of what each section might be about.
Section headings are essentially hashtags. That is, they are short, descriptive phrases that start with one or more hash signs (a.k.a. pound signs, octothropes). The number of hashes you place at the start of the line will determine the heading level. One hash gives Heading Level 1; two will give Heading Level 2, etc. If you used the number-sections: true in your YMAL header, the Heading Level controls the automatic numbering of your sections.
Keep in mind that just like hashtags, section headings are not meant to be full sentences and definitely not supposed to multiple lines long. Unlike hashtags that you find online, you will want to put spaces between words and use the appropriate case (Title, Sentence) for your document style (e.g., APA). There should be a space between the hashes and the first word of the heading.
Section headings follow a hierarchy with Heading Level 1 being the top level; Heading Level 2 is the next level down, and so forth. While you can get down to Heading Levels 5 and 6, please try to keep these to a minimum. We also do not want to skip any levels. That is, don’t use a Heading Level 3 after a Heading Level 1 but not have anything that is a Heading Level 2. This is as much for ensuring the accessibility of your document as well as helping to make sure that the auto-numbering makes sense to your readers.
3.2 Styling Text
Beyond creating headings, we can also style text. The most common text styling includes italics, boldface, creating lists, and adding links.
3.2.1 Italicizing Text
The most common usages of italics are when you are introducing a key term for the first time or when you want to add emphasis to a word or phrase. To italicize a word or phrase, you’ll need to place a single asterisk, *, on both sides of the word/phrase. For example, *sample arithmetic mean* will get rendered as sample arithmetic mean in the render/knitted document.
3.2.2 Bolding Text
Boldface text also places emphasis on a word or phrase and can be used to call out particular words or phrases in your writing. To make a word or phrase bold, you’ll need to type two underscores. _ _ (with no space between them) on both sides of the word/phrase. For example, _ _ NASA_ _ becomes NASA in the final output.
In Markdown you can also use two asterisks on either side of a term to get boldface. For example, **NASA** will also make NASA.
3.2.3 Lists
There are several different kinds of lists but the two most common are bulleted (a.k.a. unordered lists) and numbered (a.k.a. ordered lists). The major difference between the two is whether you want to convey to the reader that list elements need to be done in a specific order (i.e., ordered lists) or in any order (i.e., unordered lists).
To create a list, you’ll want to move down two lines from you preceding narrative text and then type either a dash (-) for unordered lists or a numeral followed by a period (e.g., 1.) for ordered lists. You will want to have an empty line after the last element in your list before starting your next block of test. Here are two examples.
- Apples
- Oranges
- Bananas
- Wake up
- Have breakfast
- Get ready for the day
3.2.4 Links
You can add links to your text (as appropriate) by enclosing the link text in square brackets ([ and ]) and then immediately placing the URL link inside a set of parentheses after the last square braket (no spaces). For example, the text “[Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/)” will get rendered as Markdown Cheat Sheet (Markdown Cheat Sheet | Markdown Guide, n.d.).
If you want to see further ways to style text, check out the aforementioned Markdown cheat sheet.
3.3 Writing Mathematics
When working in quantitative fields like Statistics and Data Science, we often find ourselves needing to type mathematical expressions or formula. Quarto allows us to include mathematics in our narrative text in one of two formats: inline math and display math.
3.3.1 Inline Mathematics
Inline mathematics is meant to be displayed as part of a regular sentence. For example, we might want to report that some random variable follows a Gaussian distribution with mean \(\mu=70\) and variance \(\sigma^2=4.2\).
Start your inline mathematical expression by typing a single dollar sign, $, followed by your expression; end your expression with another dollar sign, $. For example, $y=x^2+\frac{3}{4}$ will become \(y=x^2+\frac{3}{4}\).
If done correctly, the starting and ending dollar signs should appear as red text in the RStudio Desktop IDE Source view.
Need to type a dollar sign without triggering a math expression? Just preceed the dollar sign with a backslash. For example, \ $ (no space). This also works on other Markdown symbols such as the asterisk and underscore.
3.3.1.1 Greek Characters
While it might be tempting to use HTML entities for Greek characters (e.g., μ) or those found from keyboard shortcuts (e.g., µ), you need to do so with some caution. The HTML entities will only appear in the HTML output. The keyboard shortcut generated symbols may cause the Quarto document to fail to render (especially to PDF). The best practice is to use inline mathematics for Greek characters.
3.3.2 Display Mathematics
Display mathematics is for when you want to the mathematical expression to be centered on its own line. We use this when we really want to emphasize the formula.
To create display equations (centered on their own line), use two dollar signs to begin and end the expression. Thus, $ $y=x^2+\frac{3}{4}$ $ (no space between the dollar signs) will become \[y=x^2+\frac{3}{4}\]
3.3.2.1 Align Environment and Multiple Lines
If you need to create mathematical expressions that span multiple lines, you can use the align environment inside a display math mode. For example,
\begin{align*}
H_0&: y = \mu_{\bullet\bullet} + \epsilon_{ij}\\
H_1&: y = \mu\_{\bullet\bullet} + \alpha_{i} + \epsilon_{ij}\\
end{align*}will become
\[\begin{align*} H_0&: y = \mu_{\bullet\bullet} + \epsilon_{ij}\\ H_1&: y = \mu_{\bullet\bullet} + \alpha_{i} + \epsilon_{ij} \end{align*}\]
The ampersand, &, tells LaTeX to use align the lines that point.
The math display system in Quarto is connected to LaTeX (TeX). If you are familiar with that system, you can draw upon that knowledge. If you’re new to typing mathematics, no worries. Overleaf (n.d.) has a handy guide of Greek characters and mathematical symbols as well as a bunch of other math guides you can draw from.